﻿
//  Copyright (C) 2011 Luca Piccioni
// 
//  This program is free software: you can redistribute it and/or modify
//  it under the terms of the GNU General Public License as published by
//  the Free Software Foundation, either version 3 of the License, or
//  (at your option) any later version.
// 
//  This program is distributed in the hope that it will be useful,
//  but WITHOUT ANY WARRANTY; without even the implied warranty of
//  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
//  GNU General Public License for more details.
// 
//  You should have received a copy of the GNU General Public License
//  along with this program.  If not, see <http://www.gnu.org/licenses/>.

using System.Collections.Generic;
using System.IO;

namespace Derm.Raster
{
	/// <summary>
	/// Interface implemented by external plugins loaded by <see cref="ImageCodec"/>.
	/// </summary>
	public interface IImageCodecPlugin : IPlugin
	{
		#region Codec Implementation

		/// <summary>
		/// Query image file informations.
		/// </summary>
		/// <returns>
		/// A <see cref="ImageInfo"/>
		/// </returns>
		ImageInfo QueryImageInfo(Stream fs, ImageCodec.CodecCriteria criteria);

		/// <summary>
		/// Load image from file.
		/// </summary>
		/// <param name="fs">
		/// A <see cref="FileStream"/> where the image data is stored.
		/// </param>
		/// <param name="criteria">
		/// A <see cref="ImageCodec.CodecCriteria"/> that specifies parameters for loading an image stream.
		/// </param>
		/// <returns>
		/// An <see cref="Image"/> holding the image data.
		/// </returns>
		Image Load(Stream fs, ImageCodec.CodecCriteria criteria);

		/// <summary>
		/// Save image pixels to file.
		/// </summary>
		/// <param name="fs">
		/// A <see cref="System.IO.FileStream"/> which stores the image data.
		/// </param>
		/// <param name="image">
		/// A <see cref="Image"/> holding the data to be stored.
		/// </param>
		/// <param name="format">
		/// A <see cref="ImageFormat"/> that specifies the image format to used for saving <paramref name="image"/>.
		/// </param>
		/// <param name="criteria">
		/// A <see cref="ImageCodec.CodecCriteria"/> that specifies parameters for loading an image stream.
		/// </param>
		void Save(Stream fs, Image image, ImageFormat format, ImageCodec.CodecCriteria criteria);

		#endregion

		#region Plugin Support Queries

		/// <summary>
		/// Get a list of image formats supported for reading.
		/// </summary>
		IEnumerable<ImageFormat> SupportedReadImageFormats { get; }

		/// <summary>
		/// Check whether an image format is supported for reading.
		/// </summary>
		/// <param name="format">
		/// An <see cref="ImageFormat"/> that specifies the image format to test for read support.
		/// </param>
		/// <returns>
		/// A <see cref="System.Boolean"/> indicating whether <paramref name="format"/> is supported.
		/// </returns>
		bool IsReadSupported(ImageFormat format);

		/// <summary>
		/// Check whether a file stream is supported for reading.
		/// </summary>
		/// <param name="path">
		/// A <see cref="System.String"/>
		/// </param>
		/// <returns>
		/// A <see cref="System.Boolean"/>
		/// </returns>
		/// <remarks>
		/// This routine determine whether a file is supported by examining the file
		/// name extention.
		/// </remarks>
		bool IsReadSupported(string path);

		/// <summary>
		/// Get a list of image formats supported for writing.
		/// </summary>
		IEnumerable<ImageFormat> SupportedWriteImageFormats { get; }

		/// <summary>
		/// Check whether an image format is supported for writing.
		/// </summary>
		/// <param name="format">
		/// An <see cref="ImageFormat"/> that specifies the image format to test for read support.
		/// </param>
		/// <returns>
		/// A <see cref="System.Boolean"/> indicating whether <paramref name="format"/> is supported.
		/// </returns>
		bool IsWriteSupported(ImageFormat format);

		/// <summary>
		/// Check whether a file stream is supported for writing.
		/// </summary>
		/// <param name="path">
		/// A <see cref="System.String"/>
		/// </param>
		/// <returns>
		/// A <see cref="System.Boolean"/>
		/// </returns>
		/// <remarks>
		/// This routine determine whether a file is supported by examining the file
		/// name extention.
		/// </remarks>
		bool IsWriteSupported(string path);

		/// <summary>
		/// Determine the plugin priority for a certain image format.
		/// </summary>
		/// <param name="format">
		/// An <see cref="ImageFormat"/> that specifies the image format to test for priority.
		/// </param>
		/// <returns>
		/// It returns an integer value indicating the priority of this implementation respect other ones supporting the same
		/// image format. Conventionally, a value of 0 indicates a totally impartial plugin implementation; a value less than 0 indicates
		/// a more confident implementation respect other plugins; a value greater than 0 indicates a fallback implementation respect other
		/// plugins.
		/// </returns>
		int GetPriority(ImageFormat format);

		#endregion
	}
}
